blob: ca0046fc96cb8fb23b4568b2bfa05751fc65b8da (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
.. _mozilla_projects_nss_reference_nspr_functions:
NSPR functions
==============
.. container::
`NSPR <https://www.mozilla.org/projects/nspr/>`__ is a platform abstraction library that provides
a cross-platform API to common OS services. NSS uses NSPR internally as the porting layer.
However, a small number of NSPR functions are required for using the certificate verification and
SSL functions in NSS. These NSPR functions are listed in this section.
.. _nspr_initialization_and_shutdown:
`NSPR initialization and shutdown <#nspr_initialization_and_shutdown>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
NSPR is automatically initialized by the first NSPR function called by the application. Call
```PR_Cleanup`` </en-US/PR_Cleanup>`__ to shut down NSPR and clean up its resources.\ `
</en-US/PR_Init>`__
- `PR_Cleanup </en-US/PR_Cleanup>`__
.. _error_reporting:
`Error reporting <#error_reporting>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
NSS uses NSPR's thread-specific error code to report errors. Call
```PR_GetError`` </en-US/PR_GetError>`__ to get the error code of the last failed NSS or NSPR
function. Call ```PR_SetError`` </en-US/PR_SetError>`__ to set the error code, which can be
retrieved with ``PR_GetError`` later.
The NSS functions ``PORT_GetError`` and ``PORT_SetError`` are simply wrappers of ``PR_GetError``
and ``PR_SetError``.
- `PR_GetError </en-US/PR_GetError>`__
- `PR_SetError </en-US/PR_SetError>`__
.. _calendar_time:
`Calendar time <#calendar_time>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
NSS certificate verification functions take a ``PRTime`` parameter that specifies the time
instant at which the validity of the certificate should verified. The NSPR function
```PR_Now`` </en-US/PR_Now>`__ returns the current time in ``PRTime``.
- `PR_Now </en-US/PR_Now>`__
.. _interval_time:
`Interval time <#interval_time>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
The NSPR socket I/O functions ```PR_Recv`` </en-US/PR_Recv>`__ and
```PR_Send`` </en-US/PR_Send>`__ (used by the NSS SSL functions) take a ``PRIntervalTime``
timeout parameter. ``PRIntervalTime`` has an abstract, platform-dependent time unit. Call
```PR_SecondsToInterval`` </en-US/PR_SecondsToInterval>`__ or ``PR_MillisecondsToInterval`` to
convert a time interval in seconds or milliseconds to ``PRIntervalTime``.
- `PR_SecondsToInterval </en-US/PR_SecondsToInterval>`__
- `PR_MillisecondsToInterval </en-US/PR_MillisecondsToInterval>`__
.. _nspr_io_layering:
`NSPR I/O layering <#nspr_io_layering>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
NSPR file descriptors can be layered, corresponding to the layers in the network stack. The SSL
library in NSS implements the SSL protocol as an NSPR I/O layer, which sits on top of another
NSPR I/O layer that represents TCP.
You can implement an NSPR I/O layer that wraps your own TCP socket code. The following NSPR
functions allow you to create your own NSPR I/O layer and manipulate it.
- `PR_GetUniqueIdentity </en-US/PR_GetUniqueIdentity>`__
- `PR_CreateIOLayerStub </en-US/PR_CreateIOLayerStub>`__
- `PR_GetDefaultIOMethods </en-US/PR_GetDefaultIOMethods>`__
- `PR_GetIdentitiesLayer </en-US/PR_GetIdentitiesLayer>`__
- `PR_GetLayersIdentity </en-US/PR_GetLayersIdentity>`__
- `PR_PushIOLayer </en-US/PR_PushIOLayer>`__
- `PR_PopIOLayer </en-US/PR_PopIOLayer>`__
.. _wrapping_a_native_file_descriptor:
`Wrapping a native file descriptor <#wrapping_a_native_file_descriptor>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
If your current TCP socket code uses the standard BSD socket API, a lighter-weight method than
creating your own NSPR I/O layer is to simply import a native file descriptor into NSPR. This
method is convenient and works for most applications.
- `PR_ImportTCPSocket </en-US/PR_ImportTCPSocket>`__
.. _socket_io_functions:
`Socket I/O functions <#socket_io_functions>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container::
As mentioned above, the SSL library in NSS implements the SSL protocol as an NSPR I/O layer.
Users call NSPR socket I/O functions to read from, write to, and shut down an SSL connection, and
to close an NSPR file descriptor.
- `PR_Read </en-US/PR_Read>`__
- `PR_Write </en-US/PR_Write>`__
- `PR_Recv </en-US/PR_Recv>`__
- `PR_Send </en-US/PR_Send>`__
- `PR_GetSocketOption </en-US/PR_GetSocketOption>`__
- `PR_SetSocketOption </en-US/PR_SetSocketOption>`__
- `PR_Shutdown </en-US/PR_Shutdown>`__
- `PR_Close </en-US/PR_Close>`__
|
